Developer CD Series 1996 February: Tool Chest

home *** CD-ROM | disk | FTP | other *** search

/ Developer CD Series 1996 February: Tool Chest / Apple Developer CD Series Tool Chest February 1996 (Apple Computer)(1996).iso / Sample Code / AppsToGo / DTS.Lib / DTS.Lib.headers / Utilities.h < prev next >

Wrap

C/C++ Source or Header | 1994-09-22 | 60.6 KB | 1,800 lines | [TEXT/MPS ]

/*----------------------------------------------------------------------------------------- # # Apple Macintosh Developer Technical Support # # Collection of Utilities for DTS Sample code # # Program: Utilities.c.o # File: Utilities.h - Header for C Source # # Copyright © 1988-1990 Apple Computer, Inc. # All rights reserved. # -----------------------------------------------------------------------------------------*/ #ifndef __UTILITIES__ #define __UTILITIES__ #ifndef __TYPES__ #include <Types.h> #endif #ifndef __QUICKDRAW__ #include <QuickDraw.h> #endif #ifndef __DIALOGS__ #include <Dialogs.h> #endif #ifndef __FILES__ #include <Files.h> #endif #ifndef __MEMORY__ #include <Memory.h> #endif #ifndef __MENUS__ #include <Menus.h> #endif #ifndef __OSUTILS__ #include <OSUtils.h> #endif #ifndef __WINDOWS__ #include <Windows.h> #endif #include "UtilitiesCommon.h" #ifndef __STRINGUTILS__ #include "StringUtils.h" #endif #ifdef powerc #pragma options align=mac68k #endif struct PopupCtlData { MenuHandle mHandle; short mID; char mPrivate[1]; }; typedef struct PopupCtlData PopupCtlData; typedef PopupCtlData *PopupCtlDataPtr, **PopupCtlDataHandle; #ifdef powerc #pragma options align=reset #endif #define kMenuItemTxtInsert -1 #define kMenuItemNumInsert -2 #define kMenuItemSectionEnd -3 /*----------------------------------------------------------------------------------------- Global constants -----------------------------------------------------------------------------------------*/ #ifndef applec #ifndef nil #define nil 0L #endif #ifndef _WaitNextEvent #define _WaitNextEvent 0xA860 #endif #ifndef _InitGraf #define _InitGraf 0xA86E #endif #ifndef _Unimplemented #define _Unimplemented 0xA89F #endif /* #define screenActive 15 */ #endif #define kNoEvents 0 /* no events mask */ #define kDelayTime 4 /* For the delay time when flashing the menubar and highlighting a button. 4/60ths of a second*/ #define kStartPtH 2 /* offset from the left of the screen */ #define kStartPtV 2 /* offset from the top of the screen */ #define kStaggerH 12 /* staggering amounts for new windows */ #define kStaggerV 16 #define chHome '\001' /* ASCII code for the Home key */ #define chEnter '\003' /* ASCII code for Enter character */ #define chEnd '\004' /* ASCII code for the End key */ #define chHelp '\005' /* ASCII code for Help key */ #define chBackspace '\010' /* ASCII code for Backspace character */ #define chTab '\011' /* ASCII code for Tab character */ #define chPageUp '\013' /* ASCII code for Page Up key */ #define chPageDown '\014' /* ASCII code for Page Down key */ #define chReturn '\015' /* ASCII code for Return character */ #define chFunction '\020' /* ASCII code for any function key */ #define chClear '\033' /* ASCII code for Clear key (aka ESC) */ #define chEscape '\033' /* ASCII code for Escape (aka Clear) key */ #define chLeft '\034' /* ASCII code for left arrow */ #define chRight '\035' /* ASCII code for right arrow */ #define chUp '\036' /* ASCII code for up arrow */ #define chDown '\037' /* ASCII code for down arrow */ #define chFwdDelete '\177' /* ASCII code for forward delete */ #define chSpace ' ' /* ASCII code for Space character */ enum { kQDOriginal = 0, kQD8Bit, kQD32Bit }; /* For use with gQDVersion */ /*----------------------------------------------------------------------------------------- Types -----------------------------------------------------------------------------------------*/ #ifdef powerc #pragma options align=mac68k #endif struct WindowTemplate { /*template to a WIND resource*/ Rect boundsRect; short procID; Boolean visible; Boolean filler1; Boolean goAwayFlag; Boolean filler2; long refCon; Str255 title; }; typedef struct WindowTemplate WindowTemplate; typedef WindowTemplate *WindowTPtr, **WindowTHndl; #ifdef powerc #pragma options align=reset #endif #ifdef powerc #define FlushInstructionCache() #endif typedef Rect (*PositionWndProcPtr)(WindowPtr window, WindowPtr relatedWindow, Rect sizeInfo); typedef void (*DrawControlProcPtr)(ControlHandle ctl); typedef short (*GetButtonVariantProcPtr)(ControlHandle ctl, Boolean *stop); #ifdef powerc #pragma options align=mac68k #endif typedef struct PFSSpec { FSSpec fss; Str31 volName; } PFSSpec; typedef PFSSpec *PFSSpecPtr; #ifdef powerc #pragma options align=reset #endif typedef Boolean (*TrackControlProcPtr)(ControlHandle ctl, short part, EventRecord *event); typedef void (*ScrollProcPtr)(ControlHandle ctl, short part, short oldVal, short newVal); typedef struct ControlStyleInfo { short ctlID; TrackControlProcPtr trackProc; ScrollProcPtr scrollProc; short hArrowVal; short vArrowVal; short hPageVal; short vPageVal; DrawControlProcPtr drawControl; short fontSize; Style fontStyle; Str32 font; Str63 keyEquivs; Str255 balloonHelp; } ControlStyleInfo; typedef ControlStyleInfo *ControlStyleInfoPtr; /*----------------------------------------------------------------------------------------- Handy Macros/inlines -----------------------------------------------------------------------------------------*/ #ifdef false /* The c++ stuff is turned OFF!!! */ inline Point* TopLeft(Rect& r) /* provide access to rect.topLeft */ { return (Point*)(&r.top); } inline Point* BotRight(Rect& r) /* provide access to rect.botRight */ { return (Point*)(&r.bottom); } inline short HiWrd(long aLong) /* return the hi word of a long */ { return ((aLong >> 16) & 0xFFFF); } inline short LoWrd(long aLong) /* return the lo word of a long */ { return (aLong & 0xFFFF); } inline void SETPT(Point *pt,short h,short v) { (*pt).h = h; (*pt).v = v); } inline void SETRECT(Rect *r,short left,short top,short right,short bottom) { SETPT(TopLeft(*r), left, top); SETPT(BotRight(*r), right, bottom); } /* * Useful functions for testing gestalt attribute responses * * BTstBool returns a true boolean value (0 or 1), but is slower than: * BTstQ which simply returns a non-zero value if the bit is set which * means the result could get lost if assigned to a short, for example. * * arg is any integer value, bitnbr is the number of the bit to be tested. * bitnbr = 0 is the least significant bit. */ inline short BTstBool(arg, bitnbr) { return ((arg >> bitnbr) & 1); } inline long BTstQ(arg, bitnbr) { return (arg & (1 << bitnbr)); } #else #ifndef THINK_C #define QD(whatever) (qd.##whatever) #else #define QD(whatever) (whatever) #endif #define TopLeft(r) (* (Point *) &(r).top) #define BotRight(r) (* (Point *) &(r).bottom) #define HiWrd(aLong) (((aLong) >> 16) & 0xFFFF) #define LoWrd(aLong) ((aLong) & 0xFFFF) #define MIN(a, b) ((a) < (b) ? (a) : (b) ) #define MAX(a, b) ((a) > (b) ? (a) : (b) ) #define SETPT(pt, x, y) (*(pt)).h = (x); (*(pt)).v = (y) #define SETRECT(r, left, top, right, bottom) \ SETPT(&TopLeft(*(r)), (left), (top)); \ SETPT(&BotRight(*(r)), (right), (bottom)) #define offsetof(structure,field) ((unsigned long)&((structure *) 0)->field) /* * Useful macros for testing gestalt attribute responses * * BTstBool returns a true boolean value (0 or 1), but is slower than: * BTstQ which simply returns a non-zero value if the bit is set which * means the result could get lost if assigned to a short, for example. * * arg is any integer value, bitnbr is the number of the bit to be tested. * bitnbr = 0 is the least significant bit. */ #define BTstBool(arg, bitnbr) ((arg >> bitnbr) & 1) #define BTstQ(arg, bitnbr) (arg & (1 << bitnbr)) #endif /*----------------------------------------------------------------------------------------- Global variables -----------------------------------------------------------------------------------------*/ /* The following global variables are initialized by StardardInitialization to * define the environnment. This used to be a single SysEnvRec, but now, * all those variables defined in a SysEnvRec can be returned by Gestalt * (except sysVRefNum; see FindSysFolder). Note that all the variables * below will be correctly initialized whether Gestalt is available or not; * the Gestalt glue handles this. */ extern ModalFilterUPP gAlertFilterUPP; extern ModalFilterUPP gKeyEquivFilterUPP; extern short gMachineType; /* which machine this is */ extern short gSystemVersion; /* System version number */ extern short gProcessorType; /* which CPU this is */ extern Boolean gHasFPU; /* true if machine has an FPU */ extern short gQDVersion; /* major QD version #; 0 for original, 1 for color QD, 2 for 32-bit QD */ extern short gKeyboardType; /* which type of keyboard is present */ extern short gAppleTalkVersion; /* AppleTalk version number */ /* These are also handled by Gestalt. gHasPMMU has no corresponding SysEnvRec * field, but it is handled by the glue, so we include it here for completeness. * gAUXVersion will be initialized with Gestalt if present, but correctly * set even if Gestalt is not available */ extern Boolean gHasPMMU; /* true if machine has a PMMU or equivalent */ extern short gAUXVersion; /* major A/UX version number (0 if not present) */ /* * gHasWaitNextEvent is set to TRUE if the Macintosh we are running on has * WaitNextEvent implemented. We can use this in our main event loop to * determine whether to call WaitNextEvent or GetNextEvent. */ extern Boolean gHasWaitNextEvent; /* * gAppResRef is the application’s resource file reference. I need to save * this since I can open other resource files. The current resource file is * always gAppResRef unless I momentarily set it to another file to read its * resources, and then immediately restore it back. */ extern short gAppResRef; /* * gInBackground is maintained by our osEvent handling routines. Any part of * the program can check it to find out if it is currently in the background. */ extern Boolean gInBackground; /* maintained by StandardInitialization and DoEvent */ /* * gAppName holds the name of the application that's running. You can use if * for any purpose you'd like. It is also used by StandardAbout if it can't * find a string to use for the application name in a resource, so make sure * you call InitForStandardAbout if you are going to call StandardAbout. If you * call StandardInitialization, this is done for you. */ extern Str255 gAppName; /* * gSignature holds the creator signature for the running application. It follows the * same rules as those for gAppName. */ extern OSType gSignature; /* * Initial values of these global variables are set to zero or FALSE by MPW's * runtime initialization routines. If the Utilities initialization routines * have been properly called, then gUtilitiesInited will be true. If it is * not true, then the values of the above global variables are invalid. */ extern Boolean gUtilitiesInited; /* * These are global UniversalProcPtrs for AlertFilter() and KeyEquivFilter() * These are always initialized. */ extern ModalFilterUPP gAlertFilterUPP; extern ModalFilterUPP gKeyEquivFilterUPP; extern GetButtonVariantProcPtr gGetButtonVariant; /* * Use this global to add to or override the GetButtonVariant function. There there * are other controls that you would like to automatically behave like check boxes * and radio buttons, write a function that returns the correct variant, given the * control, and then set this global procPtr to it. */ /*----------------------------------------------------------------------------------------- Interface to routines -----------------------------------------------------------------------------------------*/ #ifdef __cplusplus extern "C" { #endif Rect SetWindowPlacementRect(Rect *rct); /* ¶ Overrides normal window positioning in favor of the rect passed in. INPUT: rct Pointer to rect to be used for custom window placement. OUTPUT: Rect The old window placement rect. Set the window placement rect. This rect overrides normal window positioning in favor of the rect passed in. For reference, the function also returns the old window placement rect. If nil is passed in for the new rect, then no change to the positioning rect is made. The old rect is still returned. */ short CenteredAlert(short alertID, WindowPtr relatedWindow, ModalFilterUPP filter); /* ¶ Center the alert on the same device as the related window. INPUT: alertID Resource ID of alert. relatedWindow Window to "follow" when determining which monitor or the alert. filter The alert filter. Given an Alert ID and a related window pointer, this routine will center the alert on the same device as the related window. If the related window pointer is nil, then the alert will be centered on the device that the alert would normally be placed if Alert was called directly. */ void CenterRectInRect(Rect outerRect, Rect *innerRect); /* ¶ Given two rectangles, this routine centers the second one within the first. INPUT: outerRect The rect to center within. IN/OUT: innerRect Input: The rect to center. Output: The centered rect. Given two rectangles, this routine centers the second one within the first. */ Rect CenterWindow(WindowPtr window, WindowPtr relatedWindow, Rect sizeInfo); /* ¶ Center the window on the same device as the related window. INPUT: window Window to center. relatedWindow Window to "follow" when centering. sizeInfo Min and max sizes for the window. sizeInfo.top = Minimum height of window. sizeInfo.left = Minimum width of window. sizeInfo.bottom = Maximum height of window. sizeInfo.right = Maximum width of window. If any of the above sizeInfo fields are 0, then that field has no effect on limiting the change. Given a window pointer and a related window pointer, this routine will center the window on the same device as the related window. If the related window pointer is nil, then the window will be centered on the device that the window already is. WARNING: This routine may move or purge memory. */ void CloseAnyWindow(WindowPtr window); /* ¶ Closes the indicated window. Also handles if the window is a DA window. INPUT: window The window to close. Closes the indicated window. Does the right thing, taking into account that the window may belong to a DA. WARNING: An application window is closed via a CloseWindow call. Use this call when you want to keep the storage for the window record. (Compare against DisposeAnyWindow.) */ void DisposeAnyWindow(WindowPtr window); /* ¶ Disposes the indicated window. Also handles if the window is a DA window. INPUT: window The window to dispose. Disposes of the indicated window. Does the right thing, taking into account that the window may belong to a DA. WARNING: An application window is closed via a DisposeWindow call. Use this call when you want to free up the storage for the window record. (Compare against CloseAnyWindow.) */ void DeathAlert(short errResID, short errStringIndex); /* ¶ Display an alert that tells the user an error occurred, then exit the program. INPUT: errResID Resource ID of 'STR#' resource holding death alert string. errStringIndex String # of string in 'STR#' resource. Display an alert that tells the user an error occurred, then exit the program. This routine is used as an ultimate bail-out for serious errors that prohibit the continuation of the application. */ void DeathAlertMessage(short errResID, short errStringIndex, short message); /* ¶ Display an alert that tells the user an error occurred, then exit the program. INPUT: errResID Resource ID of 'STR#' resource holding death alert string. errStringIndex String # of string in 'STR#' resource. message Error number. If non-0, it is appended to the alert text. Display an alert that tells the user an error occurred, then exit the program. This routine is used as an ultimate bail-out for serious errors that prohibit the continuation of the application. */ void ErrorAlert(short errResID, short errStringIndex); /* ¶ Display an alert that tells the user an error occurred. INPUT: errResID Resource ID of 'STR#' resource holding error alert string. errStringIndex String # of string in 'STR#' resource. Display an alert that tells the user an error occurred. */ void ErrorAlertMessage(short errResID, short errStringIndex, short message); /* ¶ Display an alert that tells the user an error occurred. INPUT: errResID Resource ID of 'STR#' resource holding error alert string. errStringIndex String # of string in 'STR#' resource. message Error number. If non-0, it is appended to the alert text. Display an alert that tells the user an error occurred. */ OSErr FindSysFolder(short *foundVRefNum, long *foundDirID); /* ¶ FindSysFolder returns real vRefNum, and the DirID of the current system folder. OUTPUT: foundVRefNum Volume refNum found is returned here. foundDirID Directory ID found is returned here. RESULT: OSErr FindSysFolder returns the (real) vRefNum, and the DirID of the current system folder. It uses the Folder Manager if present, otherwise it falls back to SysEnvirons. It returns zero on success, otherwise a standard system error. This function is only really useful for system 6 compatibility, as system 7 has this functionality. */ Handle GetAppIndResource(ResType theType, short index, OSErr *err); /* ¶ GetAppIndResource gets a resource from the application's res file by index. INPUT: theType Resource type to get. index Index into resource of type theType. OUTPUT: err Errors are returned here. RESULT: Handle The resource. GetAppIndResource gets a resource from the application's res file by index. */ Handle GetAppNamedResource(ResType theType, StringPtr name, OSErr *err); /* ¶ GetAppIndResource gets a resource from the application's res file by name. INPUT: theType Resource type to get. name Name of resource to get. OUTPUT: err Errors are returned here. RESULT: Handle The resource. GetAppIndResource gets a resource from the application's res file by name. */ Handle GetAppResource(ResType theType, short theID, OSErr *err); /* ¶ GetAppIndResource gets a resource from the application's res file by ID. INPUT: theType Resource type to get. theID ID of resource to get. OUTPUT: err Errors are returned here. RESULT: Handle The resource. GetAppResource gets a resource from the application's res file by ID. */ short GetAUXVersion(void); /* ¶ Checks for the presence of A/UX by whatever means is appropriate. OUTPUT: short Major version number of A/UX. getAUXVersion -- Checks for the presence of A/UX by whatever means is appropriate. Returns the major version number of A/UX (i.e. 0 if A/UX is not present, 1 for any 1.x.x version 2 for any 2.x version, etc. This code should work for all past, present and future A/UX systems. */ short GetButtonVariant(ControlHandle ctl); /* ¶ Returns which kind of button the control is. INPUT: ctl Handle to determine button type of. This function returns which kind of button the control is. This does more than GetCVariant in that it makes sure that the control is actually a button. It does this by comparing the defProc against the known defProc for the various button types. For 7.0, there is only one defProc for all variants, but for pre-7.0, there is one defProc value for each variant. The function handles either case. */ OSErr SimpleCanDialog(void); /* ¶ Check to see if dialogs are allowed. RESULT: OSErr Check to see if dialogs are allowed. They may not be if AppleScript is running the show. If so, then a non-0 value is returned, and you should not display the dialog. */ DialogPtr GetCenteredDialog(short id, DialogPtr storage, WindowPtr relatedWindow, WindowPtr behind); /* INPUT: id Resource ID of dialog to center. storage Pointer to dialog record area, or nil for it to be created. relatedWindow Window (or dialog) that dialog being created should follow. behind Window (or dialog) thta dialog being created should be placed behind. RESULT: DialogPtr The dialog created, or nil if failure. Given a dialog ID and a related window pointer, this routine will center the dialog on the same device as the related window. If the related window pointer is nil, then the dialog will be centered on the device that the dialog would normally be placed if GetNewDialog was called. */ WindowPtr GetCenteredWindow(short id, Ptr storage, Boolean vis, WindowPtr relWindow, WindowPtr behind, Boolean inColor, Rect sizeInfo, long refCon); /* ¶ Center the window on the same device as the related window. INPUT: id ID of 'WIND' resource. storage Pointer to space for WindowRecord, or nil to have it created. vis True if window should be created visible. relWindow Window that the new window should "follow" screen-wise. behind Window that the new window should be created behind. inColor True if window should be created as a color window. sizeInfo Min and max sizes for the window. sizeInfo.top = Minimum height of window. sizeInfo.left = Minimum width of window. sizeInfo.bottom = Maximum height of window. sizeInfo.right = Maximum width of window. If any of the above sizeInfo fields are 0, then that field has no effect on limiting the change. refCon Regular window refCon. RESULT: WindowPtr Window that was created, or nil upon failure. Given a window ID and a related window pointer, this routine will center the window on the same device as the related window. If the related window pointer is nil, then the window will be centered on the device that the window would normally be placed if GetNewWindow was called. The function is also passed the sizeInfo rect, which holds min and max size information for the window. (See GetSomeKindOfWindow.) */ Boolean GetCheckOrRadio(DialogPtr dlgPtr, short itemNo); /* ¶ Return true if dialog item is a check box or radio button. INPUT: dlgPtr Dialog whose item is being checked. itemNo Item to test to see if a checkbox or radio button. RESULT: Boolean True returned if item is a checkbox or radio button. Returns true if dialog item is a check box or radio button. */ long GetGestaltResult(OSType gestaltSelector); /* ¶ Returns the result value from Gestalt for the specified selector. INPUT: gestaltSelector Regular Gestalt selector value. RESULT: long Gestalt value. GetGestaltResult returns the result value from Gestalt for the specified selector. If Gestalt returned an error GetGestaltResult returns zero. Use of this function is only cool if we don't care whether Gestalt returned an error. In many cases you may need to know the exact Gestalt error code so then this routine would be inappropriate. */ Point GetGlobalMouse(void); /* ¶ Returns the location of the mouse in local coordinates. RESULT: Point Mouse location in local coordidates, based on the current grafPort. Returns the location of the mouse in local coordinates. It does this by calling OSEventAvail. */ Point GetGlobalTopLeft(WindowPtr window); /* ¶ Return the top left point of the window’s port in global coordinates. INPUT: window Window whose upper-left is to be returned. RESULT: Point Upper-left, in local coordinates, of the window. Given a window, this will return the top left point of the window’s port in global coordinates. Something this doesn’t include, is the window’s drag region (or title bar). This returns the top left point of the window’s content area only. */ long GetKFreeSpace(short vRefNum); /* ¶ Return the amount of free space on the volume in KBytes. INPUT: vRefNum Volume reference to get free space for. RESULT: long Amount free on volume. Return the amount of free space on the volume in KBytes. -1 is returned as the size if there is an error. */ Rect GetMainScreenRect(void); /* ¶ Return rect of main screen, i.e., the screen with the window bar. RESULT: Rect Bounding rect of main screen, including menu bar. Return rect of main screen, i.e., the screen with the window bar. */ GDHandle GetRectDevice(Rect globalRect); /* ¶ Find the greatest overlap device for the given global rectangle. INPUT: globalRect Rect to intersect with devices. GDHandle Graphics device containing the most of the rect. Find the greatest overlap device for the given global rectangle. This function assumes that you have a system that GDHandle can happen. If you call this function on other QuickDraws, you will crash. */ Rect GetRectDeviceRect(Rect globalRect); /* ¶ Find the rect of the greatest overlap device for the given global rect. INPUT: globalRect Rect to intersect devices with. RESULT: Rect Rect of device containing the most of the rect. Find the rect of the greatest overlap device for the given global rect. */ WindowPtr GetSomeKindOfWindow(PositionWndProcPtr whatKind, short windID, Ptr storage, Boolean vis, WindowPtr relatedWindow, WindowPtr behind, Boolean inColor, Rect sizeInfo, long refCon); /* INPUT: whatKind ProcPtr to window positioning routine. This function would be an application-specific replacement of GetCenteredWindow, for example. windID ID of 'WIND' resource. storage Pointer to space for WindowRecord, or nil to have it created. vis True if window should be created visible. relatedWindow Window that the new window should "follow" screen-wise. behind Window that the new window should be created behind. inColor True if window should be created as a color window. sizeInfo Min and max sizes for the window. sizeInfo.top = Minimum height of window. sizeInfo.left = Minimum width of window. sizeInfo.bottom = Maximum height of window. sizeInfo.right = Maximum width of window. If any of the above sizeInfo fields are 0, then that field has no effect on limiting the change. refCon Regular window refCon. RESULT: WindowPtr Window that was created, or nil upon failure. Given a window positioning procedure pointer, a window ID and a window pointer the window relates to, this function open a new window by either a NewCWindow or a NewWindow call, depending on the value of inColor. The window will be opened invisible, independent of what the resource says. Once the window is opened successfully, the positioning procedure is called. The positioning procedure is passed a pointer to the just-opened invisible window,a pointer to the related window, and the sizeInfo rect. The sizeInfo rect holds the minimum size in the upper-left point, and the max size in the lower-left point. It is up to the positioning procedure to move the invisible window to the correct location on the correct device. Once the positioning procedure returns, the window will be made visible if so indicated by the resource. */ WindowPtr GetStaggeredWindow(short id, Ptr storage, Boolean vis, WindowPtr relWindow, WindowPtr behind, Boolean inColor, Rect sizeInfo, long refCon); /* ¶ Stagger the window on the same device as the related window. INPUT: id ID of 'WIND' resource. storage Pointer to space for WindowRecord, or nil to have it created. vis True if window should be created visible. relWindow Window that the new window should "follow" screen-wise. behind Window that the new window should be created behind. inColor True if window should be created as a color window. sizeInfo Min and max sizes for the window. sizeInfo.top = Minimum height of window. sizeInfo.left = Minimum width of window. sizeInfo.bottom = Maximum height of window. sizeInfo.right = Maximum width of window. If any of the above sizeInfo fields are 0, then that field has no effect on limiting the change. refCon Regular window refCon. RESULT: WindowPtr Window that was created, or nil upon failure. Given a window ID and a related window pointer, this routine will stagger the window on the same device as the related window. If the related window pointer is nil, then the window will be staggered on the device that the window would normally be placed if GetNewWindow was called. The function is also passed the sizeInfo rect, which holds min and max size information for the window. (See GetSomeKindOfWindow.) */ void GetSystemInfo(void); /* ¶ Sets up some global variables for use by the utilities package and your application. This sets up some global variables for use by the utilities package and your application. If you call StandardInitialization, you don't need to call this, as it will do it for you. */ TrapType GetTrapType(short theTrap); /* ¶ Returns the type (OSType or ToolType) of the trap. INPUT: theTrap Trap to get type for. Returns the type (OSType or ToolType) of the trap. It does this by checking the bits of the trap word. */ Rect GetWindowContentRect(WindowPtr window); /* ¶ Get the global rectangle that encloses the content area of the window. INPUT: window Window to get content area rect for. RESULT: Rect Content area of rect, in global coordinates. Given a window pointer, return the global rectangle that encloses the content area of the window. */ short GetWindowCount(Boolean includeDAs, Boolean includeDLOGs, Boolean includeInvisibles); /* ¶ Counts the number of windows in the application plane. INPUT: includeDAs Include DA windows in count. includeDLOGs Include dialog windows in count. includeInvisibles Also count invisible windows. This procedure counts the number of windows in the application plane. You have the choices of also counting DAs, DLOGs, and invisible windows in this count. */ GDHandle GetWindowDevice(WindowPtr window); /* ¶ Find the greatest overlap device for the given window. INPUT: window Window to determine device for. OUTPUT: GDHandle Device containing largest portion of the window. Find the greatest overlap device for the given window. */ Rect GetWindowDeviceRect(WindowPtr window); /* ¶ Find device that contains most of the window and return device's bounding rectangle. INPUT: window Window to check against the devices. OUTPUT: Rect Bounding rect of device containing the most of the window. Given a window pointer, find the device that contains most of the window and return the device's bounding rectangle. */ Rect GetWindowDeviceRectNMB(WindowPtr window); /* ¶ Bounding rect of device containing most of the window, less menu bar. INPUT: window Window to check against the devices. OUTPUT: Rect Bounding rect of device containing the most of the window. Given a window pointer, find the device that contains most of the window and return the device's bounding rectangle, less the menu bar if it is on that device. */ Rect GetWindowStructureRect(WindowPtr window); /* ¶ Get the rectangle that surrounds the entire structure of a window. INPUT: window Window to get structure rect for. OUTPUT: Rect Bounding rect of structure region for window. This procedure is used to get the rectangle that surrounds the entire structure of a window. This is true whether or not the window is visible. If the window is visible, then it is a simple matter of using the bounding rectangle of the structure region. If the window is invisible, then the strucRgn is not correct. To make it correct, then window has to be moved way off the screen and then made visible. This generates a valid strucRgn, although it is valid for the position that is way off the screen. It still needs to be offset back into the original position. Once the bounding rectangle for the strucRgn is obtained, the window can then be hidden again and moved back to its correct location. Note that ShowHide is used, instead of ShowWindow and HideWindow. HideWindow can change the plane of the window. Also, ShowHide does not affect the hiliting of windows. */ void GlobalToLocalRect(Rect *aRect); /* ¶ Convert the global rect to local coordinates, based on the current grafPort. IN/OUT: Rect INPUT: Global rectange to convert to local. OUTPUT: Rectangle in local coordinates. Convert the global rect to local coordinates, based on the current grafPort. */ void InitToolBox(void); /* ¶ Initialize the toolbox in the “standard” way for applications. Initialize the toolbox in the “standard” way for applications. */ Boolean IsAppWindow(WindowPtr window); /* ¶ Return true if the windowKind of the window is greater than or equal to userKind. INPUT: window Window to test for user-kindness. RESULT: Boolean True if window is >= userKind. Returns TRUE if the windowKind of the window is greater than or equal to userKind. If it is less, or the window is NIL, then return FALSE. */ Boolean IsDAWindow(WindowPtr window); /* ¶ Return true if the windowKind of the window is less than zero. INPUT: window Window to check for DA-ness. OUTPUT: Boolean True if window is a DA window. Returns true if the windowKind of the window is less than zero. If not, or the window is nil, then return FALSE. */ Boolean IsScrollBar(ControlHandle ctl); /* ¶ Return true if the control is a scrollbar. INPUT: ctl Control to test to see if it is a scrollbar. RESULT: Boolean True if the control is a scrollbar. Returns TRUE if the control is a scrollbar. */ void LocalToGlobalRect(Rect *aRect); /* ¶ Convert the local rect to global coordinates, based on the current grafPort. IN/OUT: Rect INPUT: Local rectange to convert to global. OUTPUT: Rectangle in global coordinates. Convert the local rect to global coordinates, based on the current grafPort. */ char LockHandleHigh(Handle theHandle); /* ¶ Does a MoveHHi on the handle and then locks it. INPUT: theHandle Handle to lock high. RESULT: char Old state of the handle. Does a MoveHHi on the handle and then locks it. Also, the original state of the handle is returned, so you can keep it and set the handle back to it's original state with a HSetState call. */ short NumToolboxTraps(void); /* ¶ Determines the size of the Tool trap table. RESULT: short Size of the tool trap table. Determines the size of the Tool trap table. It does this by sampling a couple of trap locations and seeing which, if any are Unimplemented. */ void OutlineControl(ControlHandle button); /* ¶ Draw the default indicator around the control. INPUT: button Control to draw the indicator around. Draw the default indicator around the control. */ void OutlineDialogItem(DialogPtr dlgPtr, short item); /* ¶ Draw the default indicator around the dialog item. INPUT: dlgPtr Dialog that owns the item. item Item to draw a dialog selector around. Draw the default indicator around the dialog item. */ void PositionRectInRect(Rect outerRect, Rect *innerRect, Fixed horzRatio, Fixed vertRatio); /* ¶ Positions one rect within another, based on a ratio. INPUT: outerRect Rect to position within. horzRatio Ratio for horizontal positioning. vertRatio Ratio for vertical positioning. IN/OUT: innerRect INPUT: Rect to position. OUTPUT: Positioned rect. Given two rectangles, this routine positions the second within the first one so that the it maintains the spacing specified the the horzRatio and vertRatio parameters. In other words, to center an inner rectangle hoizontally, but have its center be 1/3 from the top of the outer rectangle, call this routine with horzRatio = FixRatio(1, 2), vertRatio = FixRatio(1, 3). */ void PullApplicationToFront(void); /* ¶ Bring the application to the front. Bring the application to the front. */ void SelectButton(ControlHandle button); /* ¶ Cause the button to look as if it has been clicked on. INPUT: button Control to flash, as if clicked on. Given the button control handle, this will cause the button to look as if it has been clicked in. This is nice to do for the user if they type return or enter to select the default item. */ void SetCheckOrRadioButton(DialogPtr dlgPtr, short itemNo, short state); /* ¶ Set the value of a dialog item. INPUT: dlgPtr Dialog whose item is to be changed. itemNo Item to change value for. state New value for the item. Handy function for setting the value of a radio button. Given a dialog pointer, and item number, and a state, this function will take care of the rest. */ Rect StaggerWindow(WindowPtr window, WindowPtr relatedWindow, Rect sizeInfo); /* ¶ Stagger the window on the same device as the related window. INPUT: window Window to stagger. relatedWindow Window to "follow" when staggering. sizeInfo Min and max sizes for the window. sizeInfo.top = Minimum height of window. sizeInfo.left = Minimum width of window. sizeInfo.bottom = Maximum height of window. sizeInfo.right = Maximum width of window. If any of the above sizeInfo fields are 0, then that field has no effect on limiting the change. This algorithm for staggering windows does quite a good job. It also is quite gnarly. Here's the deal: There are pre-designated positions that we will try when positioning a window. These slots will be tried from the upper-left corner towards the lower-right corner. If there are other windows in that slot, then we will consider that slot taken, and proceed to the next slot. A slot is determined to be taken by checking a point with a slop area. This slop area is diamond-shaped, not simply rectangular. If there is no other visible window with an upper-left corner within the slop diamond, then we are allowed to position our window there. The above rule holds true unless this forces the window to be partly off the screen. If the window ends up partly off the screen, then we give up and just put it in the first slot. */ void StandardAbout(short appNameStringID); /* ¶ Shows a standard about box. INPUT: appNameStringID ID of the 'STR ' resource which contains the application name. Shows a standard about box with the name of the application, its version number, a copyright notice, and DTS credits. Most of this information is taking from a standard DITL and the application’s 'vers' resource. The name of the application is taken either from the 'STR ' resource passed in to this routine, or from GetAppParms if that resource doesn’t exist, or you pass in -1. */ void StandardInitialization(short callsToMoreMasters); /* ¶ Do the standard AppsToGo application initializaition thing. INPUT: callsToMoreMasters Number of times MoreMasters should be called. • Initializes “gInBackGround” to FALSE. Makes the following InitXXX calls: InitGraf, InitFonts, InitWindows, InitMenus, TEInit, InitDialogs, InitCursor. • Brings application to front with 3 EventAvail calls. • Calls SysEnvirons to initialize “gMac”. Calls TrapExists to initialize “gHasWaitNextEvent”. */ void StandardMenuSetup(short MBARID, short AppleMenuID); /* ¶ Installs and draws the menus indicated by 'MBAR'(MBARID), and more. INPUT: MBARID Menu bar ID to initialize with. AppleMenuID ID of Apple menu. Used with AddResMenu. Installs and draws the menus indicated by 'MBAR'(MBARID). Adds DA’s to the menu indicated by AppleMenuID by calling AddResMenu. If the menuBar cannot be created, the alert specified by rDeathAlert is displayed. */ void InsertHierMenus(MenuHandle menu); /* ¶ Look through the menu items for hierarchical references and handle them. INPUT: menu Menu to scan for hierarchical references. Look through the menu items for hierarchical references. For each found, insert the hierarchical menu, and then recursively search that menu for hierarchical menus. This function is called by StandardMenuSetup so that all hierarchical menus are inserted at application startup time. */ void ToggleCheck(DialogPtr dlgPtr, short cChkItem); /* ¶ Toggle the value of a dialog checkbox item. INPUT: dlgPtr Dialog which contains the item to toggle. cChkItem Checkbox item to toggle. Toggle the value of a dialog checkbox item. */ Boolean TrapExists(short theTrap); /* ¶ Returns true if the trap exists. INPUT: theTrap The trap number. RESULT: Boolean True if trap exists. Returns TRUE if the trap exists (i.e., it’s callable without getting DS error 12). */ Boolean WhichControl(Point mouseLoc, long when, WindowPtr window, ControlHandle *ctlHit); /* ¶ Return which visible control mouseLoc is within, independent of contorl state. INPUT: mouseLoc Mouse location, in local coordinates. when TickCount value of when click occured. Used to determine if the click is a double click on the control. window Window containing the controls to test. OUTPUT: ctlHit The control that was hit, if any. RESULT: Boolean True if a control was hit. Returns which visible control mouseLoc is within, independent of the state of the control. Scrollbars that are inactive are not found by FindControl. */ void ZoomToWindowDevice(WindowPtr window, short maxWidth, short maxHeight, short zoomDir, Boolean front); /* ¶ Zoom the window to size appropriate for device containing most of the window. INPUT: window The window to zoom. maxWidth The maximum width that the zoom should cause. maxHeight The maximum height that the zoom should cause. zoomDir Direction of zoom (in or out). front True if window should be brought to front, in addition to zooming. Zoom the window to the size appropriate for the device that contains the most of the window. An additional feature is that you can state the maximum that a window should be zoomed, either horizontally or vertically. If you pass in a maximum of 0 for the zoom for either direction, then that direction will be zoomed to fit the device. */ pascal Boolean AlertFilter(DialogPtr dlg, EventRecord *event, short *item); /* ¶ The alert filter makes sure that that the outline for the button gets redrawn. INPUT: dlg The dialog the event is for. event The event to filter. IN/OUT: item The item related to the event/filter. RESULT: Boolean Same return result as an Alert filter. The alert filter makes sure that that the outline for the button gets redrawn. This is important if balloon help is on, as the balloon window can overlap the outline of the button and leave a portion of it erased. */ pascal Boolean KeyEquivFilter(DialogPtr dlg, EventRecord *event, short *item); /* ¶ Allows you to assign key equivalents to dialog items. INPUT: dlg The dialog the event is for. event The event to filter. IN/OUT: item The item related to the event/filter. RESULT: Boolean Same return result as an Alert filter. The key equivalent filter allows you to assign key equivalents to dialog items. Each item can have as many key equivalents as you wish. You can also specify the exact state of the modifiers that you will or won't allow. The key equivalent information is stored in the resource fork, so the key equivalents can be easily localized. This code expects the key equivalents to be in item #2, which is a StatText item that is located so the text is outside of the dialog. This allows us to put key equivalent information in the resource fork, so the key equivalents are localizable. An example save changes before closing or quitting res source with keyEquiv info would look like: resource 'DITL' (rYesNoCancel, purgeable) { { {71, 315, 91, 367}, Button { enabled, "Save" }, {0, -1000, 20, 2}, StaticText { disabled, "=S190001,=s190001,=D190003,=d190003,=.190104,1B190004" }, {71, 80, 91, 162}, Button { enabled, "Don’t Save" }, {71, 244, 91, 302}, Button { enabled, "Cancel" }, {11, 78, 61, 366}, StaticText { disabled, "Save changes to the document “^0” before ^1?" }, {11, 23, 43, 55}, Icon { disabled, 2 } } }; The document name would be the string for param #0. The text "closing" or "quitting" would be the string for param #1. The keyEquiv entry is item #2, which has a rect that pushes it out of the dialog. The string info is interpreted as to what the key/modifier combo is, and what dialog item it relates to. A single key equiv entry is 8 characters. Entries are separated by commas. If the first character of an entry is an =, then the next character is the key. If the first character isn't an =, then the first two characters are the hex value of the key. (Ex: =S or =s for save, 1B for ESC.) If the key pressed is the same as the key value for any of the entries, then the next two characters are the hex value for which modifiers to test. This modifier test value is anded with the modifier. The result is then compared to the value of the next two hex digits. If they are equal, then the modifiers are correct, as well as the key. If this is so, we have a winner. "=S190001,=s190001,=D190003,=d190003,=.190104,1B190004" The above string breaks down as follows: =S190001 =S if event keypress is an S, check the modifier values 19 check controlKey/optionKey/cmdKey 00 all modifiers we are testing for should be false 01 if above is true, keypress maps to item # 1 =s190001 Same as =S, but lowercase =D190001 Same as =S, but maps to item #3 =d190001 Same as =D, but lowercase =.190104 =. if event keypress is a period, check the modifier values 19 check controlKey/optionKey/cmdKey 01 controlKey/optionKey should be false, cmdKey should be true 04 if above is true, keypress maps to item # 4 1B190004 1B if event keypress is an ESC, check the modifier values 19 check controlKey/optionKey/cmdKey 00 all modifiers we are testing for should be false 04 if above is true, keypress maps to item # 4 */ void OffsetControl(ControlHandle ctl, short dx, short dy); /* ¶ Convenient way to move a control a specified amount. INPUT: ctl Control to offset dx change on horizontal position dy change in vertical position This function is a convenient way to move a control a specified amount. */ void DoDrawGrowIcon(WindowPtr window, Boolean horLine, Boolean verLine); /* ¶ Draws the grow icon for the window in the specified manner. INPUT: window Window to draw growIcon for. horLine True if you want the horizontal line associated with the growIcon to draw. verLine True if you want the vertical line associated with the growIcon to draw. This function draws the grow icon for the window in the specified manner. You can clip out the horizontal or vertical line that is also drawn along with the grow icon, or you can have them draw. */ void DoDrawControls(WindowPtr window, Boolean scrollBarsOnly); /* ¶ Draws all of the controls in a window, or just the scrollbar controls. INPUT: window The window whose controls are to be drawn. scrollBarsOnly If true, only scrollbar controls should be drawn. This function draws all of the controls in a window, or just the scrollbar controls. The reason for this function is that scrollbars are really tri-state, especially now with 7.0. A scrollbar can be hilighted or not, or it can be drawn in a window that isn't the frontmost of the application plane. DoDrawControls takes this third scrollbar state into consideration. */ void DoDraw1Control(ControlHandle ctl, Boolean scrollBarsOnly); /* ¶ This is where the work for scrollbar/control drawing is actually done. INPUT: window The control to draw. scrollBarsOnly If true, only draw control if scrollbar. This function is where the work for scrollbar/control drawing is actually done. DoDrawControls calls this function for each control in a window. */ ControlHandle GetPopupCtlHandle(DialogPtr theDialog, short itemNum); /* ¶ Given a dialog and its item number and, return the control handle for the popup. INPUT: theDialog The dialog that holds the popup. itemNum The item number of the popup. RESULT: ControlHandle GetPopupCtlHandle takes a dialog and its item number and (assuming it is a popup menu control) and returns the control handle for the popup. */ MenuHandle GetPopupMenuHandle(ControlHandle popupCtl); /* ¶ Given a popup control, return the menu handle from the control. INPUT: popupCtl The popup control to dereference to get the menu handle. RESULT: MenuHandle The menu handle of the popup control. GetPopupMenuHandle takes a popup control and returns the menu handle from the control. */ short GetPopupCtlValue(DialogPtr theDialog, short popItem); /* ¶ Given a dialog and its item number and, return the control handle for the popup. INPUT: theDialog The dialog that holds the popup. popItem The item number of the popup. RESULT: short The popup control value. GetPopupCtlValue returns value for the popup control. */ void SetPopupCtlValue(DialogPtr theDialog, short popItem, short value); /* ¶ Sets a new value for a popup control. INPUT: theDialog The dialog that holds the popup. popItem The item number of the popup. value The new popup control value. SetPopupCtlValue makes value the new value for the popup control. */ short SmartInsMenuItem(MenuHandle theMenu, StringPtr theText, short section, short where); /* ¶ "Intelligently" insert a menu item into a menu. INPUT: theMenu The menu to insert into. theText The text for the menu item to be inserted. section Sections are divided by menu dividing lines. This tells which section to insert the menu item into. Section 1 is all of the items before the first dividing line. where Where to insert, relative to the section. RESULT: short Menu item number from the beginning of the menu, not beginning of section. This is used to "intelligently" insert a menu item into a menu. Pass it the menu to be modified, the text of the item being added, plus where the item is to be inserted. The location to be inserted is described by two parameters: section & where. section: Indicates which group of menu items you wish to add an item to. Menu item section 1 is all of the items before the first dividing line. Menu item section 2 is all items after the first dividing line and before the second, and so on. If you have no dividing lines, you have just 1 section so pass in 1. where: Indicates the item position relative to the section. To add an item such that it is the first item in a section, pass in a 1. It will be added in front of the first item in the section. NOTE: You should never pass in a section or where parameter of 0. Negative values for "where" are magic. If where = kMenuItemTxtInsert, then it inserts the item alphabetically into the section. A where of kMenuItemNumInsert works the same as kMenuItemTxtInsert, except it treats the strings are numbers for comparison purposes. If you want to add the item to the end of a section, use kMenuItemSectionEnd. As a final goodie, SmartInsMenuItem returns the menu item # from the beginning of the menu, not section. */ short CountMSections(MenuHandle theMenu); /* ¶ Return the number of menu sections in a menu. INPUT: theMenu The menu whose sections are to be counted. RESULT: short The number of sections. Return the number of menu sections. The number of sections is equal to the number of dividing lines + 1. */ short FindMenuItem(MenuHandle theMenu, StringPtr cmpTxt); /* ¶ Find the menu item number, given the text of the menu. INPUT theMenu The menu to search for the text. cmpText The text to scan for. Find the menu item number, given the text of the menu. */ OSErr PersistFSSpec(PFSSpecPtr pfss); /* ¶ Get an FSSpec to persist when saved to disk. INPUT: pfss A persistent-FSSpec record. RESULT: OSErr Do what is necessary to get an FSSpec to persist when saved to disk. The parID will still be valid, along with the file name. The part that isn't valid is the vRefNum. This function converts the FSSpec's vRefNum to a volume name, or converts the volume name into a vRefNum. An extended FSSpec is used. The extension is, logically enough, a volume name. If the FSSpec's vRefNum is non-0, then it fills in the volume name for that vRefNum. If the vRefNum is 0, it then uses the volume name to generate a vRefNum. Prior to saving a PFSSpec to disk, call PersistFSSpec. It will fill in the volume name. After having read a PFSSpec from disk, set the vRefNum to 0 and then call PersistFSSpec. It will fill in the vRefNum that corresponds to the volume name. */ StringPtr PathNameFromDirID(long DirID, short vRefNum, StringPtr str); /* ¶ Implementation of tech note #238. INPUT: DirID Directory ID to convert to path. vRefNum Volume of path OUTPUT: str The full path name. RESULT: StringPtr The full path name. This function is straight out of tech note #238. See this note for more info. */ void InitQuickTime(void); /* ¶ Generically initializes QuickTime. Call this to generically initialize QuickTime. It sets two globals: gQTVersion QuickTime version (0 means not available). gMovieControllerComponent QuickTime movie controller component reference. */ RgnHandle LocalScreenDepthRegion(short depth); /* ¶ Same as ScreenDepthRegion, except that it localizes the region. INPUT: depth The min depth to be included in the region. RESULT: RgnHandle The region of screen area of at least given depth. This function serves the same purpose as ScreenDepthRegion, except that it localizes the region to the current port. If the global gScreenPort is not nil, then it localizes to that port. The reason for this is that the current port may be an offscreen port. If it is offscreen, then it doesn't have a direct relationship to the screen. */ void MoveStyledControl(ControlHandle ctl, short xloc, short yloc); /* ¶ Move an AppsToGo styled control. INPUT: ctl The ontrol to move. xloc The new x-location for the control. yloc The new y-location for the control. This moves an AppsToGo styled control. Don't just call MoveControl, as the control will be removed and redrawn in possibly the wrong font/size/style, etc. */ void SizeStyledControl(ControlHandle ctl, short xsize, short ysize); /* ¶ Size an AppsToGo styled control. INPUT: ctl The ontrol to move. xsize The new width for the control. ysize The new height for the control. This resizes an AppsToGo styled control. Don't just call SizeControl, as the control will be removed and redrawn in possibly the wrong font/size/style, etc. */ void SetStyledCtlValue(ControlHandle ctl, short value); /* ¶ Set the value of an AppsToGo styled control. INPUT: ctl The ontrol to move. value The new value for the control. This sets the control value for an AppsToGo styled control. Don't just call SetControlValue, as the control will be removed and redrawn in possibly the wrong font/size/style, etc. */ void ShowStyledControl(ControlHandle ctl); /* ¶ Show a hidden AppsToGo styled control. INPUT: ctl The control to show. This shows a control that is hidden. It the control is already shown, nothing is done. Don't just call ShowControl, as the control will be removed and redrawn in possibly the wrong font/size/style, etc. */ void HideStyledControl(ControlHandle ctl); /* ¶ Hide a visible AppsToGo styled control. INPUT: ctl The control to hide. This hides a control that is visible. It the control is already hidden, nothing is done. Don't just call HideControl, as the control will be removed and redrawn in possibly the wrong font/size/style, etc. */ void UseControlStyle(ControlHandle ctl); /* ¶ Set the control's grafPort's font info to that used by the control. INPUT: ctl The control whose font info is to be put into the port. If nil is passed in, the info for that port is reset. This call should bracket direct uses of a control. For example: UseControlStyle(teCtl); CTEPutPstr(teCtl, "\pThis is the new TextEdit control text."); UseControlStyle(nil); Whenever a TextEdit control has its text completely replaced, as CTEPutPStr does, the font that the TextEdit control is set to is whatever is in the grafPort. Therefore by calling UseControlStyle prior to CTEPutPStr, we place the TextEdit's custom font into the grafPort. The second call to UseControlStyle restores the grafPort's previous values. Note that UseControlStyle saves the information to restore in globals, so don't try to nest calls to UseControlStyle. */ void SetStyledCTitle(ControlHandle ctl, StringPtr title); /* ¶ Set the title for an AppsToGo styled control. INPUT: ctl The control whose title is to be changed. Set an AppsToGo control title to new text. Don't just call hideControl, as the control will be removed and redrawn in possibly the wrong font/size/style, etc. */ short GetControlID(ControlHandle ctl); /* ¶ Get the control's ID out of the control's extended control record. INPUT: ctl The control handle to get the control ID for. RESULT: short The control ID. AppsToGo allows you to assign controls a short value for an ID. If you have the control handle, this is how you convert it to the ID for that control. */ Boolean GetControlStyle(ControlHandle ctl, ControlStyleInfoPtr cinfo); /* ¶ Get the extended control record for the control. INPUT: ctl The control to get style information for. cinfo The control style record returned. RESULT: Boolean True if the control has extended style information. AppsToGo controls generally have an extended control record. To get this information, you only have this single accesssor function, which returns you all of the data in a structure. If the control has an extended record, then true is returned. If the control doesn't have an AppsToGo extended control record, then false is returned. */ OSErr SetControlStyle(ControlHandle ctl, ControlStyleInfoPtr cinfo); /* ¶ Create, replace, or remove the control's extended control record. INPUT: ctl Control whose extended control record is to modified. cinfo A styled control's extended control record. • If the control doesn't have an extended control record, then one is created for it. • If the control already has an extended control record, then it's replaced. • If the pointer is nil, then if the control has an extended control, it is removed. RESULT: OSErr Most likely memFullErr. Add, replace, or remove the control's extended style record, according to the above rules. */ void SetTrackControlProc(ControlHandle ctl, TrackControlProcPtr proc); /* ¶ Set a track control proc for the control. INPUT: ctl The control which needs a custom track procedure. proc The procedure. Below is some code from pbClock that shows one use of the control track proc: static Boolean TrackRadioProc(ControlHandle ctl, short part, EventRecord *event) { WindowPtr window; FileRecHndl frHndl; TreeObjHndl root; static ControlActionUPP cupp; window = (*ctl)->contrlOwner; frHndl = (FileRecHndl)GetWRefCon(window); root = (*frHndl)->d.doc.root; FetchClockValues(frHndl, 0); mDerefRoot(root)->timeRemaining[0] = mDerefRoot(root)->timeControl[0]; mDerefRoot(root)->timeRemaining[1] = mDerefRoot(root)->timeControl[3]; if (event->what != mouseDown) return(true); if (!cupp) cupp = (ControlActionUPP)(-1); return(TrackControl(ctl, event->where, cupp)); } The reason for the above track procedure is that the radio buttons hold some state information. It is important to know what the old radio button selection was. When the application calls IsCtlEvent, IsCtlEvent notes that the control clicked on was a radio button, and therefore automatically turns off other radio buttons in the same family. This means that the old radio button choice is lost to the application. The application could track it, but there's no reason to really. With the above track proc, the application can make sure that it is called before the old radio button is deselected. The function first determines what document/window is associated with the control. It then gets the old clock values. FetchClockValues gets the control values, and then stores them based on which radio button is selected. (Remember that the radio buttons haven't been switched yet.) It then checks the event because this function is called even for keyEquivs. (To properly emulate a click with a keyPress, this SHOULD be called.) In the case of a keypress, we return that the control was tracked. In the case of a mouseDown, we have to determine if it was tracked by calling TrackControl. */ Boolean ControlKeyEquiv(WindowPtr window, EventRecord *event, ControlHandle *retCtl, StringPtr defaultEquivs); /* ¶ Determine if a keypress is a key equivalent for any control in the window. INPUT: window The window whose controls are to be checked for key equivs. event The keypress event. defaultEquivs If there is a default button, this string is the set of key equivs for it (if it has none of its own). OUTPUT: retCtl The control whose criteria for key equivs was met by the event. RESULT: Boolean True if a control said it was a key equiv. When an event is received, if you need to determine if it is a key equivalent for any control in a window, call this. Normally you don't have to call this, as IsCtlEvent does it for you. However, there is nothing stoppin you from calling it yourself. */ #ifdef __cplusplus } #endif #endif